home *** CD-ROM | disk | FTP | other *** search
/ Software USA 4 #3 / Software USA Volume 4.03.iso / mac / Home and Office / Hi's Universal Saver / Menu Events 1.3 / Menu Events Help (text) < prev    next >
Encoding:
Text File  |  1996-03-07  |  42.3 KB  |  978 lines  |  [TEXT/R*ch]

  1.  
  2. Menu Events 1.3
  3.  
  4. March 6, 1996
  5.  
  6.  
  7.  
  8. Disclaimer and Copyright Notice
  9.  
  10.  
  11. Menu Events is a free utility which lets you control another application’s
  12. menu commands by sending it an Apple event.  The author, Ross Brown,
  13. makes no warranty, either express or implied, with respect to this
  14. software, its performance, merchantability, or suitability for any
  15. particular purpose.  People using the Menu Events utility do so at their
  16. own risk.  The author disclaims all liability for loss of data, mechanical
  17. damage, or other losses suffered while using the Menu Events utility.
  18.  
  19. Menu Events is an AWOL Software Production, Copyright © 1994-6 Ross
  20. Brown.  All rights reserved.  Permission is granted to make and distribute
  21. copies of this software, provided this disclaimer and copyright notice are
  22. preserved on all copies.  The software may not, however, be sold or
  23. distributed for profit, or included with other software which is sold or
  24. distributed for profit, without the permission of the author.
  25.  
  26. There are no site license fees for the use of Menu Events within an
  27. organization.  The author encourages you to make and distribute as many
  28. copies of the system extension as you wish, for whomever you wish, as
  29. long as it is not for profit.  Menu Events is part of a set of cooperating
  30. programs, AWOL Utilities.  The tutorial help you are reading is designed
  31. for handling by the help server application Help on Wheels, which is also
  32. part of AWOL Utilities.
  33.  
  34.  
  35.  
  36. Distribution Policy
  37.  
  38.  
  39. New versions of individual AWOL Utilities programs, including Menu
  40. Events, are available by anonymous FTP from popular archive sites
  41. including sumex-aim.stanford.edu, mac.archive.umich.edu, and their
  42. respective mirror sites, and through Usenet news group
  43. comp.binaries.mac.
  44.  
  45. Support for AWOL Utilities is through Internet mail at address
  46. ab026@freenet.carleton.ca.  The software is not available by FTP from
  47. this site.  The address for paper correspondence is AWOL Software
  48. Productions, PO Box 24207, 300 Eagleson Road, Kanata, Ontario, Canada
  49. K2M 2C3.
  50.  
  51. Macintosh users who do not have access to electronic sources of free and
  52. shareware software may obtain a copy of AWOL Utilities by sending a
  53. self-addressed stamped envelope and an 800K (or larger) formatted
  54. diskette to the author at the above address.  U.S. users are reminded that
  55. postage from Canada in 1996 is C$0.52 up to 30 grams (1 oz.), C$0.77 up
  56. to 50 grams (1 3/4 oz.), and C$1.17 up to 100 grams (3 1/2 oz.).
  57. US$0.50, US$0.75, and US$1.00 in coin is acceptable in place of stamps
  58. for the respective weights.  People outside the U.S. and Canada may send
  59. an international postal reply coupon instead of Canadian stamps (available
  60. from any post office).  Please use sturdy envelopes, preferably cardboard
  61. disk mailers.  (Mailers over 5 mm (1/5") thick require C$1.17 postage to
  62. the U.S.)
  63. Please do not send return envelopes with non-Canadian
  64. stamps, as Canada Post will not accept them.
  65.  
  66.  
  67.  
  68. About AWOL Software Productions
  69.  
  70.  
  71. AWOL Software Productions specializes in custom development of
  72. software for the Mac OS.  Since its inception in 1990, AWOL has
  73. developed a number of programs which enhance the Mac OS user
  74. experience, working in nearly every part of the Macintosh Toolbox.  If
  75. you have a short-term programming task or product idea but lack the
  76. staff to do the expert design, coding, and documentation, we invite your
  77. inquiry.
  78.  
  79. Virtual Desktop is AWOL’s best-known effort, serving the desktop
  80. expansion needs of thousands of Mac users around the world.  Later in
  81. 1996, AWOL will release a new commercial version 2.0 to replace the
  82. freeware version contained in the AWOL Utilities package.  Please contact
  83. us at ab026@freenet.carleton.ca for feature and ordering information.
  84.  
  85. Users who want more out of the Mac’s speech capabilities should check
  86. out MacYack Pro, a jointly developed package of speech tools marketed by
  87. Scantron Quality Computers (qualitycomp@aol.com; 20200 Nine Mile Rd.,
  88. St. Clair Shores, MI 48080).
  89.  
  90.  
  91.  
  92. Purpose
  93.  
  94.  
  95. The big trend these days in Macintosh software is toward more
  96. integration between applications.  Increasingly, developers achieve this
  97. integration by using the Apple event interfaces of other applications, and
  98. by defining their own suites of Apple events for other applications to use.
  99.  
  100. Because there are far more clients than servers in the world of Apple
  101. events, there is a large number of “high-level-event-aware” applications
  102. which support program linking, using Apple events to control other
  103. applications (or just to be modern), but not offering any interface of their
  104. own.  Apart from the Required suite mandated by Finder, the functionality
  105. of these applications is beyond the reach of scripting utilities and other
  106. programs that send Apple events.  Menu Events is a utility which opens up
  107. this demi-monde of dabblers and dilettantes to the glories of Apple event
  108. controllability.  Applications which are by their nature only
  109. high-level-event-aware become scriptable and recordable Apple event
  110. servers.
  111.  
  112. If you regard an application’s collective user interface in terms of a set
  113. of available functions, then take subsets according to how the user can
  114. access these functions (Command-key combination, button click, menus,
  115. and so on), you will usually find that the subset for menus is largest.  This
  116. is because menus are intended as a baseline for the user interface;
  117. however else you can do something, you should be able to do it with menus
  118. as well.  Often a function is not available in a certain mode, but a menu
  119. selection will shift the application into that mode, then another will access
  120. the function.  This conformity is an asset of the Macintosh operating
  121. system which can be exploited to offer a fairly general means of
  122. controlling other applications.
  123.  
  124.  
  125.  
  126. Who Can Use Menu Events?
  127.  
  128.  
  129. You do not need AppleScript, or any other optional software package, for
  130. Menu Events to work.  It only requires System 7.
  131.  
  132. However, it has no user interface of its own.  It only enables programs to
  133. do something they would not otherwise be able to do, namely, invoke
  134. another application’s menu commands.
  135.  
  136. Any program you write, or any application which lets you compose and
  137. send Apple events (such as a general scripting utility, or Maybe, part of
  138. AWOL Utilities), can send a Menu event to any suitably modern application
  139. and hope for a response.  Whether or not a particular application
  140. cooperates depends on how it was programmed, but any application
  141. programmed according to the published instructions of Apple Computer
  142. will cooperate, with a bit of coaxing.
  143. See the section entitled “Limitations” for more information.
  144.  
  145. Menu events can be received from any machine on the AppleTalk network,
  146. subject to the usual Users & Groups program linking permission scheme.
  147. This allows you to use Menu events to control applications from a remote
  148. location.
  149.  
  150. If you have AppleScript, you should place the “Menu Events Scripting
  151. Addition” file in your “Scripting Additions” folder.  This will allow you
  152. to use Menu events in your scripts.  (Unlike most scripting additions, this
  153. one only describes event terminology, and does not implement the event
  154. handlers themselves, so it is useless without the Menu Events extension.)
  155. “Menu Events Sample Script” shows the sort of thing you can do with the
  156. scripting addition file installed.  Before writing a script to control a
  157. target application, you should try recording its menu actions using your
  158. script editor.  If the target application supports program linking, and the
  159. Caps Lock key is down, these actions will be recorded as Menu Events
  160. script commands.
  161.  
  162.  
  163.  
  164. What Does Menu Events Do?
  165.  
  166.  
  167. Menu Events is a system extension.  Once you have placed it in your
  168. Extensions folder and restarted your Macintosh, it adds a small suite of
  169. Apple events (“Menu events”) to the set supported by every
  170. high-level-event-aware application.  Also, if the Caps Lock key is down,
  171. it alters menu selection logic so that the selection is recorded as a Menu
  172. event.  This capability allows a script editor to record menu actions as
  173. script commands.
  174.  
  175. Many people are justly wary of control panels and system extensions,
  176. because of the conflicts they often cause with System software and with
  177. each other.  These conflicts usually result from competitive trap patching.
  178.  
  179. Menu Events installs a GetNextEvent filter and patches the MenuSelect
  180. trap at system startup to enable the Apple event recording capability, and
  181. installs an Apple event handler in the system dispatch table.  The Apple
  182. event handler cannot conflict with any other, because it is bound
  183. specifically to the Menu event class.  Menu Events does patch some traps
  184. “on the fly” to simulate menu selection, but the patches remove
  185. themselves immediately.
  186.  
  187. There are three events defined in the suite, and they work as follows.
  188. See the section entitled “Menu Events Suite” for more information on the
  189. Menu Events suite.
  190.  
  191.  
  192. Query Menu List Event
  193.  
  194. This event, with no parameters, queries the menu list of the target
  195. application.  If the application is high-level-event-aware, not
  196. background-only, and has a menu bar, it will return a list of records, each
  197. containing a menu ID (integer), a title (string), an enable/disable
  198. (Boolean), and a menu definition procedure resource ID (integer)
  199. parameter.  If you do not know the IDs or titles of the target application’s
  200. menus, this is one way to find out.  (Another way is to press the Caps
  201. Lock key and record menu actions using a script editor; yet another is to
  202. use the Menu Grabber application, also part of AWOL Utilities.)  Be aware
  203. that menu IDs do not have to agree with 'MENU' resource IDs, though they
  204. often do.
  205. See the section entitled “Suggestions for Use” for more information on
  206. Menu Grabber.
  207.  
  208. System menus (Keyboard, Help, Application), hierarchical menus, and
  209. pop-up menus do not appear in this list, but the Apple menu does.
  210.  
  211. NOTE:  The standard menu definition procedure ('MDEF') resource ID is 0.
  212. A value of -1 indicates that the menu definition procedure is not a
  213. resource.  Non-standard menu definition procedures may have abnormal
  214. ways of counting, disabling, and displaying menu items, so be careful with
  215. them.
  216.  
  217.  
  218. Query Menu Event
  219.  
  220. This event, given a menu ID (integer) and/or menu title (string)
  221. parameter, queries the items of a certain target application menu.  If the
  222. application has a menu with that ID and/or title, be it a regular, system,
  223. hierarchical, or pop-up menu, it will return a list of records, one per
  224. menu item, each containing a menu item ID (integer), an item text
  225. (string), an enable/disable (Boolean), a mark character (integer), an icon
  226. ID (integer), a style value (integer), and a Command character (integer)
  227. parameter.  The items are numbered starting from 1 at the top end of the
  228. menu.  Separators appear as disabled items with an item text of “-”.
  229.  
  230. This event simulates a simple click in the application’s menu bar, to force
  231. it to bring its menus up to date.
  232.  
  233. You may optionally include Boolean parameters to indicate which modifier
  234. keys (Shift, Control, Option, Command) are pressed at the time of the
  235. simulated menu bar click, in case this makes a difference in the content of
  236. the menu.
  237.  
  238. This event does work for menus which use a non-standard menu definition
  239. procedure ('MDEF'), but the results may or may not reflect what you see
  240. when you pull down the menu, depending on how the procedure was
  241. programmed.
  242.  
  243. This event brings the target application to the front before forcing the
  244. menu bar click upon it.  If the sender was on the same machine, and was
  245. previously in front, it returns to the front after the menu query is
  246. complete.
  247. See the section entitled “How Does Menu Events Work?” for more
  248. information about the method by which Menu Events activates the target
  249. application.
  250.  
  251.  
  252. Select Menu Item Event
  253.  
  254. This event, given a menu ID (integer) and/or menu title (string)
  255. parameter and a menu item ID (integer) and/or menu item text (string)
  256. parameter, asks the application to act as though the user pulled down that
  257. menu and selected that item.  This does not work for the Keyboard and
  258. Application menus, which are not under the control of the application, nor
  259. for the upper (System-defined) part of the Help menu, but it works for
  260. any regular, application-defined, enabled menu item.
  261.  
  262. If you use the menu item text parameter to specify the menu item to
  263. select, be sure to match any special characters in the text, especially the
  264. ellipsis ('…') character which often appears at the end of the string,
  265. which is not the same as three period characters, despite its appearance.
  266.  
  267. You may optionally include Boolean parameters to indicate which modifier
  268. keys (Shift, Control, Option, Command) are pressed at the time of the
  269. simulated menu item selection, in case this makes a difference in the
  270. effect of the selection.
  271.  
  272. This event does work for menus which use a non-standard menu definition
  273. procedure ('MDEF'), but the results may or may not reflect what happens
  274. when you select from the menu, depending on how the procedure was
  275. programmed.
  276.  
  277. This event brings the target application to the front before forcing the
  278. menu selection upon it.  If the sender was on the same machine, and was
  279. previously in front, it returns to the front after the menu action is
  280. complete.
  281. See the section entitled “How Does Menu Events Work?” for more
  282. information about the method by which Menu Events activates the target
  283. application.
  284.  
  285.  
  286.  
  287. How Does Menu Events Work?
  288.  
  289.  
  290. When you send a Query Menu List event, the ideal application dispatches
  291. the resulting high-level event as an Apple event without looking at it.  The
  292. event handler provided by Menu Events forms a reply to the query on the
  293. basis of the application’s menu list structure.  Through all of this, the
  294. application stays in the background or in the foreground, wherever it was
  295. before.
  296.  
  297. When you send a Query Menu or Select Menu Item event, the same things
  298. happen, but the event handling is more complex.
  299.  
  300. First, it verifies that the given menu is valid.  If not, it returns
  301. noSuchMenuErr.
  302.  
  303. Second, it asks for the application to be brought to the front for user
  304. interaction, because it could be dangerous to feed the target application a
  305. menu bar click while it is in the background, something that never happens
  306. in normal operation.  If it is refused, it returns errAENoUserInteraction.
  307.  
  308. Third, it patches some traps so that it can gain control of menu bar clicks.
  309. If it finds that the patches are already in place, meaning that an earlier
  310. Menu event is still pending, it returns menuEventPendingErr.
  311.  
  312. Fourth, if everything is OK, it posts an event to simulate a mouse click in
  313. the menu bar, with modifier keys if specified.  The patched traps tell the
  314. application that no menu item was selected.  The patches then remove
  315. themselves.  This step is solely to ensure that the application brings its
  316. menus up to date.
  317.  
  318. Fifth (in the case of a Select Menu Item event), it verifies that the given
  319. menu item is valid and enabled.  If not, it returns noSuchMenuErr,
  320. noSuchMenuItemErr, or menuItemDisabledErr.  If the menu has a
  321. non-standard menu definition procedure, its way of counting or disabling
  322. items may differ from the norm.  Menu Events assumes that the count and
  323. enable/disable flags are set in the normal fashion.
  324.  
  325. Sixth (in the case of a Select Menu Item event), it posts an event to
  326. simulate another mouse click in the menu bar, with modifier keys if
  327. specified.  The patched traps tell the application that the given item was
  328. selected.  The patches then remove themselves.  From there, it is exactly
  329. as though the user had actually made the selection.
  330.  
  331. NOTE:  When replying to any of the three event types, Menu Events
  332. includes a null “tattoo” parameter to prove that it handled the event,
  333. rather than some handler supplied by the application.  Many Microsoft
  334. applications, for example, bind their own handler over all Apple event
  335. classes, preventing Menu Events from working.  (The handler wouldn’t be
  336. a problem if it returned errAEEventNotHandled when faced with an
  337. unknown Apple event, as it should.)
  338.  
  339.  
  340. User Interaction Policy
  341.  
  342. The Apple Event Manager implements a complicated but sensible model for
  343. joint sender/receiver control over user interaction.  Menu Events doesn’t
  344. know which menu selections will really require user interaction, but even
  345. if it did, it would still have to request user interaction just to bring the
  346. target application to the front, where an application always expects to be
  347. when it sees a mouse-down event.
  348.  
  349. The sending program must set the kAECanInteract or kAEAlwaysInteract
  350. flag in the sendMode parameter to AESend, in order to achieve user
  351. interaction.  It should also set the kAECanSwitchLayer flag, allowing the
  352. target application to come to the front without having to post a
  353. notification request.  If the target application is in the background, and
  354. receives a Menu event with this flag not set, it may go into a notification
  355. wait state, disrupting its usual background event processing behavior.
  356.  
  357. If both the sending program and target application are in the background,
  358. the kAECanSwitchLayer flag has no effect, and the notification request is
  359. posted anyway.  Since your sending program is indirectly instigating a
  360. user interaction, it should call AEInteractWithUser before sending the
  361. Menu event, if there is any chance that it will be in the background at the
  362. time.  Another approach would be to call SetFrontProcess to activate the
  363. target application before sending it a Menu event.
  364.  
  365. If the target application is in that rare user interaction state,
  366. kAEInteractWithSelf, where it disallows interaction requested by any
  367. other process, the Menu event handler will respect that state, and refuse
  368. the event.
  369.  
  370. If the sending and receiving applications are on different machines, the
  371. usual program linking checks apply, namely, Sharing Setup (on/off),
  372. Users & Groups (permission to user), and Finder’s Sharing (permission to
  373. application).
  374.  
  375. If the Menu Events extension is locked, using Finder’s Get Info dialog, then
  376. only target applications which explicitly allow interaction with all
  377. processes can be controlled by remote senders.  If it is not locked, and if
  378. it sees that the user interaction state is kAEInteractWithLocal, which is
  379. the default value, it will momentarily change it to kAEInteractWithAll, so
  380. that events sent from a remote machine are not rejected.  This trick is
  381. necessary for Menu Events to be useful with most target applications,
  382. because most will assume the default interaction state, not expecting any
  383. remote sender to require user interaction.  The icon displayed by Menu
  384. Events at startup shows whether or not the lock is in effect.
  385.  
  386. IMPORTANT NOTE:  Users of machines where Menu Events is installed
  387. should be careful about which users and applications are enabled for
  388. remote program linking.  In particular, guest users should not be allowed
  389. to do program linking unless Menu Events is locked.
  390.  
  391.  
  392. Apple Event Recording Capability
  393.  
  394. When you are using a high-level-event-aware application on a machine
  395. where Menu Events is installed, menu item selection behavior is modified
  396. if the Caps Lock key is down at the time you release the mouse button.
  397. Menu Events will create a Select Menu Item Apple event to represent the
  398. selection (including parameters for any modifier keys which were
  399. pressed), so that a script editor can record the event as a script
  400. command.  A gentle “twang” sound confirms that this has happened.
  401. Whether or not it succeeds in recording the event, the menu selection will
  402. be processed in the usual way.
  403.  
  404. If the application is scriptable in its own right, a script editor may record
  405. two commands when you select an item from its menus.  To prevent this
  406. duplication, you can use the item’s Command-key equivalent (if any), or
  407. release the Caps Lock key, to suppress the recording capability.
  408.  
  409. If an application seems to be misinterpreting or not receiving menu
  410. selections, try again with the Caps Lock key up.  The command will not be
  411. recorded, but should work as usual.
  412.  
  413. NOTE:  While receiving a Select Menu Item event does simulate a menu
  414. selection, it does not cause a Select Menu Item script command to be
  415. recorded.
  416.  
  417.  
  418.  
  419. Suggestions for Use
  420.  
  421.  
  422. Menu Events is distributed as part of a free set of cooperating programs,
  423. AWOL Utilities.  This section explains how Menu Events can work in
  424. conjunction with the other programs.
  425.  
  426.  
  427. Help on Wheels
  428.  
  429. Help on Wheels is an efficient and full-featured help server which displays
  430. help files on behalf of client applications.  The help file you are reading is
  431. distributed alongside the Menu Events extension file as a separate Help on
  432. Wheels document.
  433.  
  434. Because Menu Events is not an application, its help support is limited.  To
  435. read this help, press the Help or Command-? key while the machine is
  436. starting up, and release the key once you see the Menu Events icon with a
  437. help balloon on it.  The help server will open to display the help file after
  438. startup is complete.
  439.  
  440.  
  441. Maybe
  442.  
  443. Maybe, the Finder alias enhancer, has an option allowing you to script a
  444. single Apple event and choose its target.  This Apple event will be sent
  445. just before the alias target is opened or printed.  In this way, you can
  446. achieve the effect of sending a simple Menu event by opening the
  447. converted alias.
  448.  
  449. Maybe does not require AppleScript or any other scripting system to send
  450. a Menu event.  Many programs, including all kinds of scripting utilities,
  451. offer a similar opportunity to send Menu events to any target application
  452. you choose.
  453.  
  454.  
  455. Menu Grabber
  456.  
  457. AWOL Utilities also contains an application, Menu Grabber, which uses
  458. Menu events to swap any target application’s menu bar over its own.
  459. This allows you to command most of the application’s functions from a
  460. remote location, although you will not see anything but the menus.  For
  461. most target applications, Menu Grabber will only be able to select menu
  462. items from a remote machine if the target’s copy of Menu Events was
  463. unlocked at startup.
  464. See the section entitled “User Interaction Policy” for more information
  465. about the effect of locking the Menu Events extension.
  466.  
  467. When Menu Grabber grabs a menu, it adds a disabled item to show the
  468. menu ID.  This may help you if you are writing a program or script to send
  469. a Menu event to the application.
  470.  
  471.  
  472.  
  473. Menu Events Suite
  474.  
  475.  
  476. The following is a formal description of the Menu Events suite, in the form
  477. used in the Apple Event Registry.
  478.  
  479. NOTE:  The C header file “Menu Events.h” contains the constant
  480. definitions which appear here.  The “Menu Events Scripting Addition” file
  481. contains an 'aete' resource which records the following dictionary
  482. information, for the benefit of scripting packages such as AppleScript.
  483. This package also includes a sample script, “Menu Events Sample
  484. Script,” which demonstrates the usage of the following events and
  485. parameters.
  486.  
  487.  
  488. Apple events defined in the Menu Events suite
  489.  
  490. Name              Requested action
  491.  
  492. Query Menu List   List all application-defined menus
  493. Query Menu        List all items in a menu
  494. Select Menu Item  Perform a menu command
  495.  
  496.  
  497. Query Menu List - list all application-defined menus
  498.  
  499. A Query Menu List Apple event asks the application to return a list of
  500. records containing information about all menus defined by the application
  501. in its menu bar.  This information includes the Apple menu, but not the
  502. Help, Keyboard, or Application menus.
  503.  
  504. Event Class       kMEEventClass
  505.  
  506. Event ID          kAEMEQueryMenuList
  507.  
  508. Parameters        none
  509.  
  510. Reply Parameters
  511.  
  512. keyDirectObject
  513.                   Description:  A list of Apple event
  514.                                 records, one for each
  515.                                 menu, each containing the
  516.                                 following parameters
  517.                   Descriptor Type:  typeAEList
  518.                   Required or Optional?  Required
  519.  
  520.    keyMenuID
  521.                   Description:  The ID of the menu, not
  522.                                 necessarily equal to the
  523.                                 ID of the 'MENU' resource
  524.                                 it may have come from
  525.                   Descriptor Type:  typeShortInteger
  526.                   Required or Optional?  Required
  527.    keyMenuTitle
  528.                   Description:  The title of the menu, as
  529.                                 it appears in the menu bar
  530.                   Descriptor Type:  typeChar
  531.                   Required or Optional?  Required
  532.    keyMenuEnabled
  533.                   Description:  Whether or not the menu, as
  534.                                 a whole, is enabled
  535.                   Descriptor Type:  typeBoolean
  536.                   Required or Optional?  Required
  537.    keyMenuMDEFID
  538.                   Description:  The ID of the menu definition
  539.                                 procedure ('MDEF') resource,
  540.                                 ordinarily 0; -1 signifies
  541.                                 that the definition procedure
  542.                                 is not a resource
  543.                   Descriptor Type:  typeShortInteger
  544.                   Required or Optional?  Required
  545.  
  546. keyMenuEventsTattoo
  547.                   Description:  A null parameter to verify
  548.                                 that Menu Events handled
  549.                                 the event
  550.                   Descriptor Type:  typeNull
  551.                   Required or Optional?  Required
  552.  
  553. Result Codes
  554.                   mBarNFnd        -126    The application has
  555.                                           no menu bar
  556.  
  557.  
  558. Query Menu - list all items in a menu
  559.  
  560. A Query Menu Apple event asks the application to return a list of records
  561. containing information about all items in a given menu (selected by ID
  562. and/or title).  It requests user interaction to bring the application to the
  563. front, then posts mouse events to simulate a click in the menu bar, with
  564. modifier key states as specified, to force the application to update its
  565. menus, then reads the items from the given menu.  This information is
  566. complete enough to reconstruct the menu, except for the icon resources
  567. referenced by the keyMenuItemIcon parameter.
  568.  
  569. Event Class       kMEEventClass
  570.  
  571. Event ID          kAEMEQueryMenu
  572.  
  573. Parameters
  574.  
  575. keyMenuID
  576.                   Description:  The ID of the menu, as
  577.                                 returned by a Query Menu
  578.                                 List Apple event
  579.                   Descriptor Type:  typeShortInteger
  580.                   Required or Optional?  Optional
  581. keyMenuTitle
  582.                   Description:  The title of the menu, as
  583.                                 returned by a Query Menu
  584.                                 List Apple event
  585.                   Descriptor Type:  typeChar
  586.                   Required or Optional?  Optional
  587. NOTE:  Either keyMenuID or keyMenuTitle, or both, must be specified.
  588. keyShiftKeyPressed
  589.                   Description:  Whether the Shift key is
  590.                                 pressed at the time of the
  591.                                 simulated menu bar click
  592.                   Descriptor Type:  typeBoolean
  593.                   Required or Optional?  Optional
  594.                   Default Value:  false
  595. keyControlKeyPressed
  596.                   Description:  Whether the Control key is
  597.                                 pressed at the time of the
  598.                                 simulated menu bar click
  599.                   Descriptor Type:  typeBoolean
  600.                   Required or Optional?  Optional
  601.                   Default Value:  false
  602. keyOptionKeyPressed
  603.                   Description:  Whether the Option key is
  604.                                 pressed at the time of the
  605.                                 simulated menu bar click
  606.                   Descriptor Type:  typeBoolean
  607.                   Required or Optional?  Optional
  608.                   Default Value:  false
  609. keyCommandKeyPressed
  610.                   Description:  Whether the Command key is
  611.                                 pressed at the time of the
  612.                                 simulated menu bar click
  613.                   Descriptor Type:  typeBoolean
  614.                   Required or Optional?  Optional
  615.                   Default Value:  false
  616.  
  617. Reply Parameters
  618.  
  619. keyDirectObject
  620.                   Description:  A list of Apple event
  621.                                 records, one for each
  622.                                 item, each containing the
  623.                                 following parameters
  624.                   Descriptor Type:  typeAEList
  625.                   Required or Optional?  Required
  626.  
  627.    keyMenuItemID
  628.                   Description:  The ID of the item, numbered
  629.                                 from 1 at the top of the menu
  630.                   Descriptor Type:  typeShortInteger
  631.                   Required or Optional?  Required
  632.    keyMenuItemText
  633.                   Description:  The text of the item, as
  634.                                 it appears in the menu
  635.                   Descriptor Type:  typeChar
  636.                   Required or Optional?  Required
  637.    keyMenuItemEnabled
  638.                   Description:  Whether or not the item is
  639.                                 enabled
  640.                   Descriptor Type:  typeBoolean
  641.                   Required or Optional?  Required
  642.    keyMenuItemMark
  643.                   Description:  The mark character of the
  644.                                 item, in the lower byte
  645.                   Descriptor Type:  typeShortInteger
  646.                   Required or Optional?  Required
  647.    keyMenuItemIcon
  648.                   Description:  The icon number of the item,
  649.                                 which is 256 less than the
  650.                                 resource ID of the 'ICON' or
  651.                                 'cicn' resource
  652.                   Descriptor Type:  typeShortInteger
  653.                   Required or Optional?  Required
  654.    keyMenuItemStyle
  655.                   Description:  The style value of the item,
  656.                                 in the lower byte
  657.                   Descriptor Type:  typeShortInteger
  658.                   Required or Optional?  Required
  659.    keyMenuItemCmd
  660.                   Description:  The Command-key equivalent
  661.                                 character of the item, in the
  662.                                 lower byte
  663.                   Descriptor Type:  typeShortInteger
  664.                   Required or Optional?  Required
  665.  
  666. keyMenuEventsTattoo
  667.                   Description:  A null parameter to verify
  668.                                 that Menu Events handled
  669.                                 the event
  670.                   Descriptor Type:  typeNull
  671.                   Required or Optional?  Required
  672.  
  673. Result Codes
  674.                   mBarNFnd        -126    The application has
  675.                                           no menu bar
  676.                   errAENoUserInteraction
  677.                                   -1713   The application is
  678.                                           refusing to interact
  679.                                           with other processes
  680.                                           or (if Menu Events
  681.                                           extension is locked)
  682.                                           with remote processes
  683.                   noSuchMenuErr   -15950  The application has
  684.                                           no such menu
  685.                   menuMismatchErr
  686.                                   -15955  The given menu ID
  687.                                           and menu title
  688.                                           do not match
  689.  
  690.  
  691. Select Menu Item - perform a menu command
  692.  
  693. A Select Menu Item event simulates the selection of a command (selected
  694. by item ID and/or item text) from a menu (selected by ID and/or title).  It
  695. requests user interaction to bring the application to the front, then posts
  696. mouse events to simulate the selection of the given menu item, with
  697. modifier key states as specified.  If the Menu event is correctly handled,
  698. and the application reacts to the mouse events in the usual way, the result
  699. is as if the user had actually selected that menu item.  Interaction will fail
  700. if the application refuses to interact with other processes
  701. (kAEInteractWithSelf mode), or, if the application is on another machine
  702. and the Menu Events extension has been locked, if it refuses to interact
  703. with remote processes (kAEInteractWithLocal mode).
  704.  
  705. Event Class       kMEEventClass
  706.  
  707. Event ID          kAEMESelectMenuItem
  708.  
  709. Parameters
  710.  
  711. keyMenuID
  712.                   Description:  The ID of the menu, as
  713.                                 returned by a Query Menu
  714.                                 List Apple event
  715.                   Descriptor Type:  typeShortInteger
  716.                   Required or Optional?  Required
  717. keyMenuTitle
  718.                   Description:  The title of the menu, as
  719.                                 returned by a Query Menu
  720.                                 List Apple event
  721.                   Descriptor Type:  typeChar
  722.                   Required or Optional?  Optional
  723. NOTE:  Either keyMenuID or keyMenuTitle, or both, must be specified.
  724. keyMenuItemID
  725.                   Description:  The ID of the item, numbered
  726.                                 from 1 at the top of the menu
  727.                   Descriptor Type:  typeShortInteger
  728.                   Required or Optional?  Optional
  729. keyMenuItemText
  730.                   Description:  The text of the item, as
  731.                                 it appears in the menu
  732.                   Descriptor Type:  typeChar
  733.                   Required or Optional?  Optional
  734. NOTE:  Either keyMenuItemID or keyMenuItemText, or both, must be
  735. specified.
  736. keyShiftKeyPressed
  737.                   Description:  Whether the Shift key is
  738.                                 pressed at the time of the
  739.                                 simulated menu selection
  740.                   Descriptor Type:  typeBoolean
  741.                   Required or Optional?  Optional
  742.                   Default Value:  false
  743. keyControlKeyPressed
  744.                   Description:  Whether the Control key is
  745.                                 pressed at the time of the
  746.                                 simulated menu selection
  747.                   Descriptor Type:  typeBoolean
  748.                   Required or Optional?  Optional
  749.                   Default Value:  false
  750. keyOptionKeyPressed
  751.                   Description:  Whether the Option key is
  752.                                 pressed at the time of the
  753.                                 simulated menu selection
  754.                   Descriptor Type:  typeBoolean
  755.                   Required or Optional?  Optional
  756.                   Default Value:  false
  757. keyCommandKeyPressed
  758.                   Description:  Whether the Command key is
  759.                                 pressed at the time of the
  760.                                 simulated menu selection
  761.                   Descriptor Type:  typeBoolean
  762.                   Required or Optional?  Optional
  763.                   Default Value:  false
  764.  
  765. Reply Parameters
  766.  
  767. keyMenuEventsTattoo
  768.                   Description:  A null parameter to verify
  769.                                 that Menu Events handled
  770.                                 the event
  771.                   Descriptor Type:  typeNull
  772.                   Required or Optional?  Required
  773.  
  774. Result Codes
  775.                   mBarNFnd        -126    The application has
  776.                                           no menu bar
  777.                   errAENoUserInteraction
  778.                                   -1713   The application is
  779.                                           refusing to interact
  780.                                           with other processes
  781.                                           or (if Menu Events
  782.                                           extension is locked)
  783.                                           with remote processes
  784.                   noSuchMenuErr   -15950  The application has
  785.                                           no such menu
  786.                   noSuchMenuItemErr
  787.                                   -15951  The menu has no
  788.                                           such item
  789.                   menuItemDisabledErr
  790.                                   -15952  The item is
  791.                                           disabled
  792.                   menuEventPendingErr
  793.                                   -15953  Another Menu event
  794.                                           is already pending
  795.                                           on this application
  796.                   menuMismatchErr
  797.                                   -15955  The given menu ID
  798.                                           and menu title
  799.                                           do not match
  800.                   menuItemMismatchErr
  801.                                   -15956  The given menu item ID
  802.                                           and menu item text
  803.                                           do not match
  804.  
  805.  
  806. Constants defined in the Menu Events suite
  807.  
  808. Constant               Value
  809.  
  810. kAEMEQueryMenu         'qmn '
  811. kAEMEQueryMenuList     'qmn#'
  812. kAEMESelectMenuItem    'semi'
  813. keyCommandKeyPressed   'comk'
  814. keyControlKeyPressed   'conk'
  815. keyMenuEnabled         'mnen'
  816. keyMenuEventsTattoo    'Mænu'
  817. keyMenuID              'mnid'
  818. keyMenuItemCmd         'micm'
  819. keyMenuItemEnabled     'mien'
  820. keyMenuItemIcon        'miic'
  821. keyMenuItemID          'miid'
  822. keyMenuItemMark        'mima'
  823. keyMenuItemStyle       'mist'
  824. keyMenuItemText        'mite'
  825. keyMenuMDEFID          'mndf'
  826. keyMenuTitle           'mnti'
  827. keyOptionKeyPressed    'optk'
  828. keyShiftKeyPressed     'shik'
  829. kMEEventClass          'Mænu'
  830. menuEventPendingErr    -15953
  831. menuItemDisabledErr    -15952
  832. menuItemMismatchErr    -15956
  833. menuMismatchErr        -15955
  834. noSuchMenuErr          -15950
  835. noSuchMenuItemErr      -15951
  836.  
  837.  
  838.  
  839. Limitations
  840.  
  841.  
  842. Some applications refuse to submit to the trickery of Menu Events.  The
  843. prime example is any version of Finder which predates the Power
  844. Macintosh (version 7.1.2).  It is not truly an Apple event server, and it
  845. only respects events of known types.  Any other high-level event is not
  846. replied to, and the send will time out.  ResEdit 2.1.1 is similar.  Some
  847. Microsoft applications handle Apple events in a non-standard fashion,
  848. binding their own event handlers over all Apple event classes, and
  849. therefore should not be targeted.
  850.  
  851. The only way to know for sure is to try the ones you are interested in
  852. controlling.  Certainly, anything you write yourself is a candidate, as long
  853. as you follow the practices suggested in Apple documentation, namely:  Be
  854. high-level-event-aware.  Always be ready to accept and dispatch an
  855. Apple event.  Assume that any high-level event you don’t recognize is an
  856. Apple event, and dispatch it as such.  If an unknown event reaches your
  857. wildcard event handler, return errAEEventNotHandled, so that system
  858. event handlers can get a crack at it.  Don’t deny other programs on the
  859. same machine the right to request user interaction, which is the default.
  860.  
  861. Another limitation you should know about is that Menu Events can’t
  862. operate dialogs and alerts which the target application may post in
  863. response to the menu action.  If the menu item text ends in an ellipsis
  864. ('…') character, you can bet that the application will post a dialog or alert
  865. box.  It is then up to the local user to operate the controls.
  866.  
  867. If the target machine is under the influence of a screen saver or security
  868. package which would present a modal dialog in response to a mouse click,
  869. then Query Menu and Select Menu Item events will time out.  The same is
  870. true if the target machine is already showing a modal dialog, preventing
  871. Menu Events from activating the target application.
  872.  
  873. A known conflict exists between Menu Events and Help on Wheels.  If you
  874. send a Menu event to an application which does a casual help display
  875. before performing the menu action, and if the help server is running,
  876. problems may occur with the application.  The problem is that the Menu
  877. event’s user interaction ends when the receiving application sends an
  878. Apple event to the help server, causing it to return to the background.  If
  879. the menu action causes a call to the Standard File Manager or any other
  880. code which should not be called when in the background, the application
  881. may hang.
  882.  
  883.  
  884.  
  885. Programmer Notes
  886.  
  887.  
  888. Write to the author at the above address if you want to know more about
  889. the Menu Events extension or how it was programmed.
  890.  
  891.  
  892.  
  893. Acknowledgements
  894.  
  895.  
  896. Thanks to C.K. Haun and the other folks at Apple Developer Technical
  897. Support who put together those clever little code snippets which give
  898. folks like me such odd ideas.
  899.  
  900. Special thanks to the many fine people who beta-tested this software,
  901. including Ken Linger, Chris Reynolds, Michele Marques, Chris Kaltwasser,
  902. James Edward Davis, and Leonard Rosenthol, and to Fred Terry for his
  903. hospitality at the MacScripting mailing list.
  904.  
  905.  
  906.  
  907. Revision History
  908.  
  909.  
  910. 1.3 (March 6, 1996)
  911. •  Public AWOL Utilities 1.3 release.
  912. •  Allowed menus and menu items to be specified using string parameters,
  913. with or without the corresponding numeric ID parameters.  An error is
  914. returned if the numeric and string parameters do not match.
  915. •  Added support for modifier keys (Shift, Control, Option, Command) in
  916. the Query Menu event.
  917. •  Improved application compatibility by simulating a menu bar click, to
  918. force the application to update its menus, before reading the contents of a
  919. menu in response to a Query Menu or Select Menu Item event.
  920. •  Changed the response to a menu selection with the Caps Lock key down
  921. to a simple Apple event recording action, instead of having the target
  922. application send itself a Menu event to invite recording.
  923. •  Added an error string parameter to the reply event when an error
  924. occurs.
  925. •  Moved the error codes from the -21000 range to the -15950 range, so
  926. that errors are reported sensibly in AppleScript alerts.
  927. •  Rewrote “Menu Events Sample Script” to make use of the new optional
  928. string parameters.
  929.  
  930. 1.2 (October 17, 1994)
  931. •  Public AWOL Utilities 1.2 release.
  932. •  No revisions.
  933.  
  934. 1.1.2 (April 19, 1994)
  935. •  Added support for script recording by forcing high-level-event-aware
  936. applications to send themselves Menu events when the user selects a
  937. menu item and the Caps Lock key is down.
  938. •  Added support for modifier keys (Shift, Control, Option, Command) in
  939. the Select Menu Item event.
  940. •  Removed the nonStandardMenuErr (-21004) code in favor of the new
  941. keyMenuMDEFID parameter in the reply to the Query Menu List event, to
  942. improve compatibility with target applications which use slightly
  943. non-standard menu definition procedures.
  944.  
  945. 1.1.1 (April 11, 1994)
  946. •  Added “Menu Events Scripting Addition” and “Menu Events Sample
  947. Script” in place of “Menu Events 'aete'” resource file.
  948.  
  949. 1.1 (March 28, 1994)
  950. •  Public AWOL Utilities 1.1 release.
  951. •  Documented that Menu Events works with Finder 7.1.2.
  952.  
  953. 1.0.7 (March 13, 1994)
  954. •  Menu Events Help presents a useful message if the user tries to open or
  955. print it when the help server is absent.
  956.  
  957. 1.0.6 (February 27, 1994)
  958. •  Added protection against loading duplicate copies of the extension.
  959.  
  960. 1.0.5 (February 6, 1994)
  961. •  Improved compatibility with At Ease and other applications which flush
  962. mouse-down events when they become active.
  963.  
  964. 1.0.4 (January 30, 1994)
  965. •  If the Shift key is pressed on startup, the extension will not be loaded.
  966. If the Help or Command-? key is pressed, the extension will delay up to
  967. one second to let the user release the key(s).
  968.  
  969. 1.0.3 (January 19, 1994)
  970. •  Added “Menu Events 'aete'” resource file.
  971.  
  972. 1.0.2 (January 11, 1994)
  973. •  Fixed bug which sent the target application into a notification wait state
  974. if it received a Menu event from a remote sender.
  975.  
  976. 1.0.1 (December 31, 1993)
  977. •  Initial AWOL Utilities 1.0.1 release.
  978.